
=HTTPTransport=


HTTPTransport is a prototype which provides a low-level HTTP server.

The transport detects an external HTTP protocol requests arriving on
a configured TCP/IP port and constructs a root request which it
issues into its containing space.
The root request identifier is the URL of the external HTTP request
(Refer to the 
[[doc:tpt:http:HTTPBridge#Configuration|HTTPBridge]] 
documentation to see how to map the external URL to the normalized <code>res:/</code> scheme).
The transport wraps the low-level HTTPRequest and HTTPResponse objects into a 
HTTPRequestResponseRepresentation and adds it as the
[[doc:physicalreference:request:analysis#Primary_Argument|primary argument]].
The transport uses the SOURCE verb for the root request (The HTTP ''method''
is available through the 
[[doc:tpt:http:httpRequest#httpRequest:.2Fmethod|httpRequest:]] address space).

{endpoint}jetty.HTTPTransport{/endpoint}


==Configuration==

An HTTP transport is instantiated from its prototype
in a space by using the following declaration
(Refer to the 
[[doc:tpt:http:HTTPBridge#Configuration|HTTPBridge]]
documentation for a configuration example of the transport and bridge)

{xml}
<transport>
	<prototype>HTTPTransport</prototype>
</transport>
{/xml}

The HTTPTransport will issue a request for the resource
<code>res:/etc/HTTPServerConfig.xml</code>
using  the SOURCE verb to obtain its configuration information.
This resource must be present in space in which the transport
is configured.  

HTTPServerConfig.xml is a XML document containing configuration 
information for the Jetty HTTP server library. 
Please consult the Jetty web site 
([http://docs.codehaus.org/display/JETTY/jetty.xml]) for details about the various
configuration options.
The following is  an example used as the default for the Front-end fulcrum.


{xml}<Configure id="Server" class="org.mortbay.jetty.Server">
  <Set name="ThreadPool">
    <New class="org.mortbay.thread.BoundedThreadPool">
      <Set name="minThreads">4</Set>
      <Set name="maxThreads">10</Set>
      <Set name="lowThreads">2</Set>
    </New>
  </Set>
  <Call name="addConnector">
    <Arg>
      <New class="org.mortbay.jetty.nio.SelectChannelConnector">
        <Set name="port">8080</Set>
        <Set name="maxIdleTime">30000</Set>
        <Set name="Acceptors">2</Set>
        <Set name="statsOn">false</Set>
        <Set name="confidentialPort">8081</Set>
        <Set name="lowResourcesConnections">5000</Set>
        <Set name="lowResourcesMaxIdleTime">5000</Set>
      </New>
    </Arg>
  </Call>
	
	<Call name="addHandler">
		<Arg>
			<New id="NetKernelHandler" class="org.netkernel.http.transport.NetKernelHandler"/>
		</Arg>
	</Call>
	

  <Set name="stopAtShutdown">false</Set>
  <Set name="sendServerVersion">true</Set>
  <Set name="sendDateHeader">true</Set>
  <Set name="gracefulShutdown">1000</Set>
</Configure>{/xml}

The HttpTransport '''must''' have one Jetty handler with id of '''NetKernelHandler''' - this is the handler which issues requests into the ROC address space. 

==TCP/IP Port==

The TCP/IP port used by the Jetty server is set in a configuration line;
the following sets the port to <code>8080</code>:

{xml}<Set name="port">8080</Set>{/xml}

==SSL==

To add SSL sockets examine /etc/HTTPServerConfig.xml in the front-end fulcrum and uncomment the following
optional connector...

{xml}
  <Call name="addConnector">
    <Arg>
      <New class="org.mortbay.jetty.security.SslSelectChannelConnector">
        <Set name="port">8443</Set>
        <Set name="maxIdleTime">30000</Set>
        <Set name="Acceptors">2</Set>
        <Set name="confidentialPort">8443</Set>
        <Set name="lowResourcesConnections">100</Set>
        <Set name="lowResourceMaxIdleTime">5000</Set>
        <Set name="statsOn">true</Set>
        <Set name="keystore">/home/pjr/workspace/install/keystore</Set>
        <Set name="password">test123</Set>
        <Set name="truststore">/home/pjr/workspace/install/keystore</Set>
        <Set name="trustPassword">test123</Set>
        <Set name="keyPassword">test123</Set>
      </New>
    </Arg>
  </Call>
{/xml}

A Java keystore must be configured to hold your SSL certificate and '''must''' be referenced using a regular file path and '''not''' a URI. 
For details see the [http://docs.codehaus.org/display/JETTY/How+to+configure+SSL|Jetty Wiki].

==HTAccess  Support==

The HTTP Transport can be configured to use Apache ''htaccess'' based control
by using a different class for the ''NetKernelHandler''.
Within the resource <code>res:/etc/HTTPServerConfig.xml</code>, change the
''NetKernelHandler'' to the following:

{xml}
<Call name="addHandler">
	<Arg>
		<New id="NetKernelHandler" class="org.netkernel.http.transport.NetKernelHandlerHTAccess"/>
	</Arg>
</Call>
{/xml}

When a request is received by the transport, 
the '''NetKernelHandlerHTAccess'''  handler will first search for
a resource named '''htaccess''' within the URL path of the received HTTP request prior to admitting
the request.
For example, if the transport receives a request for <code>http://localhost:8080/</code> the handler will issue
a request for the resource <code>res:/htaccess</code> within the HTTPOverlay wrapped space.
(This handler extends the underlying Jetty 
''org.mortbay.jetty.security.HTAccessHandler'' and is able to search in the ROC domain for '''htaccess'''
files.)

===htaccess search procedure===

{callout}
The resource identifier is
htaccess and not .htaccess.
The identifier '''does not''' include
a leading dot character '.'
{/callout}
The handler searches for an htaccess resource at the deepest level first and works it way
upwards until the parent path is searched.
For example, if the transport receives a request for <code>http://localhost:8080/first/second/index.html</code>
then it will sequentially issue a SOURCE request for the following identifiers:

* res:/first/second/htaccess
* res:/first/htaccess
* res:/htaccess

The search will stop when the first htaccess resource is located.
If no htaccess resource is discovered then it is assumed that no access constraint is 
active and the request is admitted.

===htaccess contents===
{callout}
If you need to include the password file in a module you
can dynamically generate the contents of the htaccess
resource and include the physical location of the
password file.
See the 
{luckysearch}Can I determine the physical location of a relative module file?|FAQ{/luckysearch}
on the topic.
{/callout}

The htaccess resource should be a text file organized as lines.

{literal}
AuthType Basic
AuthName "Access Controlled"
AuthUserFile /home/pjr/workspace/install/htpass
<Limit GET POST>
satisfy all
order deny,allow
require user test
</Limit>
{/literal}

Here significant configuration parameters are:

*'''AuthType''' - sets the type of authentication to use. Valid values are ''Basic'' and ''Digest''.
*'''AuthName''' - sets the realm name and is generally used as the title for a password dialog box displayed by a browser. Any value is acceptable, however it helps to provide the user some context.
*'''AuthUserFile''' - '''must be''' a physical file location ('''not''' a URI) that includes username:password combination entries in the Apache password file format. Such a file can be created and managed with the Apache  '''htpasswd''' tool.
*'''AuthGroupFile''' - '''must be''' a physical file location ('''not''' a URI) that provides group access settings.

A full list of directives can be found on the
[http://httpd.apache.org/docs/1.3/mod/directives.html|Apache Web Site].

===Example===

Suppose you have a simple static web resource set defined in a module with a <fileset>...

{xml}
<rootspace>
	<fileset>
		<glob>website/*</glob>
	</fileset>
</rootspace>
{/xml}

To provide HTAccess control over this site you would use the ''org.netkernel.http.transport.NetKernelHandlerHTAccess'' as your HTTPTranport handler.
You would add a file called ''htaccess'' to your module directory '''/website/''' with contents..

{literal}
AuthType Basic
AuthName "Access Controlled"
AuthUserFile /home/pjr/workspace/install/htpass
<Limit GET POST>
satisfy all
order deny,allow
require user test
</Limit>
{/literal}


==NCSA standard request logging==

To add NCSA standard request logging, 
add the following to the Jetty configuration file:

{xml}<Call name="addHandler">
	<Arg>
		<New id="Logger" class="org.mortbay.jetty.handler.RequestLogHandler">
			 <Set name="requestLog">
				 <New id="RequestLogImpl" class="org.mortbay.jetty.NCSARequestLog">
				      <Set name="filename">./log/NetKernelHTTP_yyyy_mm_dd.log</Set>
					  <Set name="filenameDateFormat">yyyy_MM_dd</Set>
					  <Set name="retainDays">90</Set>
					  <Set name="append">true</Set>
					  <Set name="extended">true</Set>
					  <Set name="logCookies">false</Set>
					  <Set name="LogTimeZone">GMT</Set>
					</New>
			 </Set>
		 </New>
	</Arg>
</Call>
{/xml}


